<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Bytevectors</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="Ranges.xhtml" title="Ranges"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Bytevectors" epub:type="subchapter" id="Bytevectors">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Bytevectors</h2>
          </div>
        </div>
      </div>
      <p><em class="firstterm">Bytevectors</em> represent blocks of binary data. They are
fixed-length sequences of bytes, where a <em class="replaceable"><code>byte</code></em> is an exact
integer in the range [0, 255]. A bytevector is typically more
space-efficient than a vector containing the same values.
</p>
      <p>The length of a bytevector is the number of elements that
it contains. This number is a non-negative integer that is
fixed when the bytevector is created. The valid indexes of
a bytevector are the exact non-negative integers less than
the length of the bytevector, starting at index zero as with
vectors.
</p>
      <p>The <code class="literal">bytevector</code> type is equivalent to the <code class="literal">u8vector</code>
<a class="link" href="Uniform-vectors.xhtml" title="Uniform vectors">uniform vector</a> type, but is specified
by the R7RS standard.
</p>
      <p>Bytevectors are written using the notation <code class="literal">#u8(byte . . . )</code>.
For example, a bytevector of length 3 containing the byte
0 in element 0, the byte 10 in element 1, and the byte 5 in
element 2 can be written as following:
</p>
      <pre class="screen">#u8(0 10 5)
</pre>
      <p>Bytevector constants are self-evaluating, so they do not
need to be quoted in programs.
</p>
      <p class="synopsis" kind="Type"><span class="kind">Type</span><span class="ignore">: </span><a id="idm139667874042976" class="indexterm"/> <code class="function">bytevector</code></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>The type of bytevector objects.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Constructor"><span class="kind">Constructor</span><span class="ignore">: </span><a id="idm139667874040000" class="indexterm"/> <code class="function">bytevector</code> <em class="replaceable"><code><em class="replaceable"><code>byte</code></em></code></em> <em class="replaceable"><code>…</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Return a newly allocated bytevector whose elements contain the given
arguments.  Analogous to <code class="literal">vector</code>.
</p>
          <pre class="screen">(bytevector 1 3 5 1 3 5)  ⇒  #u8(1 3 5 1 3 5)
(bytevector)  ⇒  #u8()
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874035120" class="indexterm"/> <code class="function">bytevector?</code> <em class="replaceable"><code><em class="replaceable"><code>obj</code></em></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Return <code class="literal">#t</code> if <em class="replaceable"><code>obj</code></em> is a bytevector, <code class="literal">#f</code> otherwise.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874030400" class="indexterm"/> <code class="function">make-bytevector</code> <em class="replaceable"><code>k</code></em></p>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874027600" class="indexterm"/> <code class="function">make-bytevector</code> <em class="replaceable"><code>k</code></em> <em class="replaceable"><code>byte</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>The <code class="literal">make-bytevector</code> procedure returns a newly allocated
bytevector of length <em class="replaceable"><code>k</code></em>. If <em class="replaceable"><code>byte</code></em> is given, then all elements
of the bytevector are initialized to <em class="replaceable"><code>byte</code></em>,
otherwise the contents of each element are unspecified.
</p>
          <pre class="screen">(make-bytevector 2 12) ⇒ #u8(12 12)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874021616" class="indexterm"/> <code class="function">bytevector-length</code> <em class="replaceable"><code>bytevector</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns the length of <em class="replaceable"><code>bytevector</code></em> in bytes
as an exact integer.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874017776" class="indexterm"/> <code class="function">bytevector-u8-ref</code> <em class="replaceable"><code>bytevector</code></em> <em class="replaceable"><code>k</code></em> </p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>It is an error if <em class="replaceable"><code>k</code></em> is not a valid index of <em class="replaceable"><code>bytevector</code></em>.
Returns the <em class="replaceable"><code>k</code></em>th byte of <em class="replaceable"><code>bytevector</code></em>.
</p>
          <pre class="screen">(bytevector-u8-ref ’#u8(1 1 2 3 5 8 13 21) 5)
  ⇒ 8
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874011808" class="indexterm"/> <code class="function">bytevector-u8-set!</code> <em class="replaceable"><code>bytevector</code></em> <em class="replaceable"><code>k</code></em> <em class="replaceable"><code>byte</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>It is an error if <em class="replaceable"><code>k</code></em> is not a valid index of <em class="replaceable"><code>bytevector</code></em>.
Stores <em class="replaceable"><code>byte</code></em> as the <em class="replaceable"><code>k</code></em>th byte of <em class="replaceable"><code>bytevector</code></em>.
</p>
          <pre class="screen">(let ((bv (bytevector 1 2 3 4)
  (bytevector-u8-set! bv 1 3)
  bv)
  ⇒ #u8(1 3 3 4)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667874005056" class="indexterm"/> <code class="function">bytevector-copy</code> <em class="replaceable"><code>bytevector</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns a newly allocated bytevector containing the bytes
in <em class="replaceable"><code>bytevector</code></em> between <em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em>.
</p>
          <pre class="screen">(define a #u8(1 2 3 4 5))
(bytevector-copy a 2 4))
    ⇒ #u8(3 4)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873998912" class="indexterm"/> <code class="function">bytevector-copy!</code> <em class="replaceable"><code>to</code></em> <em class="replaceable"><code>at</code></em> <em class="replaceable"><code>from</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Copies the bytes of bytevector<em class="replaceable"><code>from</code></em> between <em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em>
to bytevector <em class="replaceable"><code>to</code></em>, starting at <em class="replaceable"><code>at</code></em>. The order in which bytes
are copied is unspecified, except that if the source and destination overlap,
copying takes place as if the source is first
copied into a temporary bytevector and then into the destination.
This is achieved without allocating storage
by making sure to copy in the correct direction in such
circumstances.
</p>
          <p>It is an error if <em class="replaceable"><code>at</code></em> is less than zero or greater than the length
of <em class="replaceable"><code>to</code></em>.
It is also an error if <code class="literal">(- (bytevector-length <em class="replaceable"><code>to</code></em>) <em class="replaceable"><code>at</code></em>)</code>
is less than <code class="literal">(- <em class="replaceable"><code>end</code></em> <em class="replaceable"><code>start</code></em>)</code>.
</p>
          <pre class="screen">(define a (bytevector 1 2 3 4 5))
(define b (bytevector 10 20 30 40 50))
(bytevector-copy! b 1 a 0 2)
b        ⇒ #u8(10 1 2 40 50)
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873987040" class="indexterm"/> <code class="function">bytevector-append</code> <em class="replaceable"><code>bytevector...</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns a newly allocated bytevector whose elements are
the concatenation of the elements in the given bytevectors.
</p>
          <pre class="screen">(bytevector-append #u8(0 1 2) #u8(3 4 5))
        ⇒  #u8(0 1 2 3 4 5)
</pre>
        </blockquote>
      </div>
      <section class="sect2" title="Converting to or from strings" epub:type="division" id="idm139667873983184">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Converting to or from strings</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873982096" class="indexterm"/> <code class="function">utf8-&gt;string</code> <em class="replaceable"><code>bytevector</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>This procedure decodes the bytes of a bytevector between <em class="replaceable"><code>start</code></em>
and <em class="replaceable"><code>end</code></em>, interpreting as a UTF-8-encoded string,
and returns the corresponding string.
It is an error for <em class="replaceable"><code>bytevector</code></em> to contain invalid UTF-8 byte sequences.
</p>
            <pre class="screen">(utf8-&gt;string #u8(#x41))  ⇒ "A"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873975984" class="indexterm"/> <code class="function">utf16-&gt;string</code> <em class="replaceable"><code>bytevector</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873972224" class="indexterm"/> <code class="function">utf16be-&gt;string</code> <em class="replaceable"><code>bytevector</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873968464" class="indexterm"/> <code class="function">utf16le-&gt;string</code> <em class="replaceable"><code>bytevector</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>These procedures interpret their &lt;var&gt;bytevector&lt;/var&gt; argument as
a UTF-16 encoding of a sequence of characters,
and return an istring containing that sequence.
</p>
            <p>The bytevector subrange given to <code class="literal">utf16-&gt;string</code>
may begin with a byte order mark (BOM); if so, that BOM
determines whether the rest of the subrange is to be
interpreted as big-endian or little-endian; in either case,
the BOM will not become a character in the returned string.
If the subrange does not begin with a BOM, it is decoded using
the same implementation-dependent endianness used by
<code class="literal">string-&gt;utf16</code>.
</p>
            <p>The <code class="literal">utf16be-&gt;string</code> and <code class="literal">utf16le-&gt;string</code>
procedures interpret their inputs as big-endian or little-endian,
respectively.  If a BOM is present, it is treated as a normal
character and will become part of the result.
</p>
            <p>It is an error if <code class="literal">(- <em class="replaceable"><code>end</code></em> <em class="replaceable"><code>start</code></em>)</code> is odd,
or if the bytevector subrange contains invalid UTF-16 byte sequences.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873959024" class="indexterm"/> <code class="function">string-&gt;utf8</code> <em class="replaceable"><code>string</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>This procedure encodes the characters of a string between
<em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em> and returns the corresponding bytevector,
in UTF-8 encoding.
</p>
            <pre class="screen">(string-&gt;utf8 "λ")     ⇒ " #u8(#xCE #xBB)
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873953440" class="indexterm"/> <code class="function">string-&gt;utf16</code> <em class="replaceable"><code>string</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873949680" class="indexterm"/> <code class="function">string-&gt;utf16be</code> <em class="replaceable"><code>string</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667873945920" class="indexterm"/> <code class="function">string-&gt;utf16le</code> <em class="replaceable"><code>string</code></em> [<em class="replaceable"><code>start</code></em> [<em class="replaceable"><code>end</code></em>]]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>These procedures return a newly allocated (unless empty)
bytevector containing a UTF-16 encoding of the given substring.
</p>
            <p>The bytevectors returned by <code class="literal">string-&gt;utf16be</code>
and <code class="literal">string-&gt;utf16le</code>
do not contain a byte-order mark (BOM);
<code class="literal">string-&gt;utf16be</code>&gt; returns a big-endian encoding,
while <code class="literal">string-&gt;utf16le</code> returns a little-endian encoding.
</p>
            <p>The bytevectors returned by <code class="literal">string-&gt;utf16</code>
begin with a BOM that declares an implementation-dependent
endianness, and the bytevector elements following that BOM
encode the given  substring using that endianness.
</p>
            <p><span class="emphasis"><em>Rationale:</em></span>
These procedures are consistent with the Unicode standard.
Unicode suggests UTF-16 should default to big-endian, but
Microsoft prefers little-endian.
</p>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Bytevectors.xhtml#idm139667873983184">Converting to or from strings</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Data-structures.xhtml">Data structures</a></p>
        <p>
        Previous: <a accesskey="p" href="Uniform-vectors.xhtml">Uniform vectors</a></p>
        <p>
        Next: <a accesskey="n" href="Ranges.xhtml">Ranges</a></p>
      </div>
    </footer>
  </body>
</html>
